# Updating an existing Custom Field

Updates an existing custom field.
### Parameters that cannot be updated
Note that the `unique_constraint` and `value_type` parameters cannot be updated.
They are set during the process of [creating a custom field](/tag/Custom-Fields#operation/create-custom-field).
### Updating choices
This endpoint also allows you to update the list of choices for a custom field with
[single or multiple choices](/tag/Custom-Field-Choices). For important details
regarding how this endpoint affects the list of available choices and how to avoid
creating duplicate choices, see the description of the `choice` body parameter.
This endpoint returns structured Custom Field objects.
As with all Kantata OX API endpoints, the returned data will be referenced in sorted order in the `results` array
and will be indexed by ID in the `custom_fields` top-level JSON key.
Please see our [Response Format](#section/Response-Format) section for more information.

Endpoint: PUT /custom_fields/{id}
Version: 1.0.0

## Path parameters:

  - `id` (integer, required)
    The ID of the Model.

## Query parameters:

  - `include` (string)
    Any of the below associations can be included in your request by providing the `include` param, e.g. `include=association1,association2`.
- `choices` (CustomFieldChoice) - Includes the ID of a Custom Field's choices.
- `creator` (User) - Includes the ID of a Custom Field's creator.
- `custom_field_set` (CustomFieldSet) - Includes the ID of the Custom Field Set that a field belongs to.
- `external_references` (ExternalReference) - Includes references to external integrations for this object.

## Request fields (application/json):

  - `custom_field` (object)

  - `custom_field.name` (string)
    The name of the field.

  - `custom_field.default_text` (string)
    The message in an empty custom field, before a `string`, `date`, `number`, or `currency`  value is entered in.
This only appears in the UI.

  - `custom_field.choices` (array)
    The list of [choices](/tag/Custom-Field-Choices) a user can select from,
for a custom field's value(s). Setting this field updates a custom field's
complete list of choices; it behaves as an overwrite.
**Include all existing choices in your request, whether you are updating their `label` or not.**
Any choices not included in your request *will be deleted* from the custom field.

**How to avoid creating duplicate choices**

Choices have two attributes, a `label` and an `ID`. Different choices can have the same `label`,
but every choice has a unique `ID`. To properly update an existing choice within a list, you must specify the `ID`
of the choice you want to change. If you do not, a new choice with a unique, new `ID` is created instead.

For example:

```
custom_field_choices: {
  ....
  choices: [
    { "label": "Choice A", "id": "180291" },
    { "label": "Choice B", "id": "180301" },
    { "label": "Choice C" }
  ]
  ....
}
```

Choices in the UI appear in the same order as listed in the array.

The 1st choice is an existing choice with an ID of `180291`, and is either staying or being updated to `Choice A`.
The 2nd choice is an existing choice with an ID of `180301`, and is either staying or being updated to `Choice B`.
The 3rd choice is a new choice to create, `Choice C`, and its unique ID will be returned in the response.

  - `custom_field.choices.label` (string)
    You can think of a label as the actual value a user can select for the custom field.

*Note:* Different choices can have the same `label`.

  - `custom_field.choices.id` (integer)
    The unique ID of an existing choice(s). If you do not specify the `ID` of an existing choice in an update request,
a new choice with a unique, new `ID` is generated instead. Use this parameter to avoid replacing
existing choices with new ones.

  - `custom_field.custom_field_set_id` (integer)
    The ID of the [Custom Field Set](/tag/Custom-Field-Sets) that the field belongs to.
When a set ID is not specified, the field is added to a Project set titled 'Default Project Set'.
This means it becomes a Project field.

  - `custom_field.write_access` (string)
    The permission level required for a user to create, update, or delete a custom field value for a subject.

  - `custom_field.read_access` (string)
    The `read_access` [permission setting on each custom field](https://mavenlink.zendesk.com/hc/en-us/articles/202924760#see)
determines the minimum permission needed to view a custom field and its value.
* `Workspace` (Project), `Resource`, and `Story` (Task) custom fields are project-specific objects,
so their minimum permissions are set at the [project level](https://mavenlink.zendesk.com/hc/en-us/articles/115002779293-Project-Permissions):
  - `project_collaboration` (default)
  - `time_logging`
  - `financial`
  - `project_admin`

Most account-level permissions supercede project-level permissions. Therefore, Account Administrators
are able to view all Project, Resource, and Task custom fields and values across the account,
regardless of project participation or `read_access` settings.
* `Estimate`, `WorkspaceGroup` (Group), and `User` custom fields are account-wide objects,
so their minimum permissions are set at the [account level](https://mavenlink.zendesk.com/hc/en-us/articles/203041364):
  - `account_collaboration`
  - `project_creator`
  - `project_lead`
  - `reports_viewer`
  - `reports_viewer_with_cost`
  - `account_admin` (default).

## Response 200 fields (application/json):

  - `count` (integer)

  - `meta` (object)

  - `meta.count` (integer)

  - `meta.page_count` (integer)

  - `meta.page_number` (integer)

  - `meta.page_size` (integer)

  - `results` (array)

  - `results.key` (string)

  - `results.id` (string)

## Response 400 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 401 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 403 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 404 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 422 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 503 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)